大家好！歡迎來到「Build on Google AI」工程挑戰的第 17 天。

昨天我們用 Google ADK 的 response_schema 成功壓制了 LLM 的「話癆」屬性，產出了嚴謹的 API 規格。今天，我們要將這項「結構化魔法」應用在一個看似充滿感性與創意，實則需要極高工程精準度的領域：自動化影音分鏡表 (Video Storyboard) 生成。

在打造自動化短影音產線時，我們經常會遇到一個痛點：LLM 給的腳本太像「散文」了。
如果我們要將 Agent 的產出直接拋給文字轉語音 (TTS) API 生成旁白，或是拋給圖片/影片生成模型 (如 Imagen 3 或 Veo) 產生畫面，我們需要的是時間軸、畫面與聲音完全分離且對齊的資料庫結構，而不是一段純文字。

讓我們用 ADK 的巢狀 Schema (Nested Schema) 來解決這個挑戰！

第一步：設計「視聽對齊」的巢狀 Pydantic Schema
分鏡表是一個天然的巢狀結構：一支影片 (Storyboard) 包含多個分鏡 (Scenes)，每個分鏡都有獨立的時間、畫面與聲音。

我們透過 Pydantic 定義這個結構，並巧妙利用 Field(description="...") 來「暗示」模型該如何填寫這些欄位。這比在 Prompt 裡寫長篇大論有效得多。

from pydantic import BaseModel, Field
from typing import List

# 1. 定義單一分鏡 (Scene) 的結構
class StoryboardScene(BaseModel):
    scene_number: int = Field(description="分鏡編號，從 1 開始")
    duration_seconds: int = Field(description="該分鏡的預估秒數，通常介於 3 到 8 秒")
    visual_description: str = Field(description="極度詳細的畫面視覺描述（Prompt 級別），包含主體、光影、場景")
    camera_movement: str = Field(description="運鏡指示，如：Zoom In, Pan Left, Static 等")
    voiceover: str = Field(description="旁白台詞。如果沒有旁白請留空字串")
    sound_effects: str = Field(description="音效或背景音樂指示，如：鍵盤敲擊聲、轉場音效")

# 2. 定義完整影片 (Storyboard) 的結構
class VideoStoryboard(BaseModel):
    video_title: str
    target_platform: str = Field(description="如 YouTube Shorts, TikTok 等")
    total_duration_seconds: int
    scenes: List[StoryboardScene] # 巢狀結構：分鏡陣列

第二步：打造「導演 Agent」 (Director Agent)
接下來，我們在 Google ADK 中實例化這個 Agent，將剛才設計好的 VideoStoryboard 綁定為它的強制輸出格式。

from google.adk import Agent

# 初始化導演 Agent
director_agent = Agent(
    name="director_agent",
    model="gemini-2.5-pro", # 創意企劃與複雜結構對齊需要 Pro 級別的推理能力
    instruction="你是一位專業的短影音廣告導演。請根據主題，規劃節奏緊湊、視覺衝擊力強的分鏡腳本。必須精準分配每個分鏡的秒數，確保視覺與旁白完美對齊。",
    response_schema=VideoStoryboard
)

第三步：見證結構化輸出的威力
現在，我們只需要給導演 Agent 一個非常簡短的主題，它就會吐出完美格式化的 Python 物件，可以直接無縫串接下一階段的微服務。

prompt = "請幫我企劃一支 20 秒的 YouTube Shorts 短影音，主題是『未來已來：Google ADK(Agent Development Kit) 帶來的革命性開發體驗』，要求 Cyberpunk 科技感、快節奏運鏡剪輯與震撼轉場音效。"

# 執行 Agent
storyboard = director_agent.invoke(prompt)

print(f"🎬 影片標題: {storyboard.video_title}")
print(f"⏱️ 總時長: {storyboard.total_duration_seconds} 秒\n")

# 直接迭代分鏡陣列，提取後端需要的資料
for scene in storyboard.scenes:
    print(f"[分鏡 {scene.scene_number}] (時長: {scene.duration_seconds}s)")
    print(f"🎥 運鏡: {scene.camera_movement}")
    print(f"👁️ 畫面: {scene.visual_description}")
    print(f"🗣️ 旁白: {scene.voiceover}")
    print("-" * 30)

為何這段程式碼如此迷人？
這意味著，你可以輕易寫一個迴圈，把 scene.voiceover 批次送到 Google Cloud TTS 產生語音檔；同時把 scene.visual_description 轉換為英文後，送到 Imagen 3 產生分鏡圖，最後由 FFmpeg 自動拼裝成影片。全自動的 AIGC 產線，就建立在這個嚴謹的 Schema 之上。

使用 Gemini Omni 1.1 Flash 生成影片

https://www.youtube.com/shorts/74Hlrur8kMk

小結
今天，我們利用 ADK 與巢狀 Schema，成功將「創意企劃」轉譯成了可直接執行的「工程規格」，打通了 AI 自動生成影音的任督二脈。